---
title: 从 Docusaurus 迁移到 Astro
description: 将现有的 Docusaurus 项目迁移到 Astro 的提示
sidebar:
  label: Docusaurus
type: migration
stub: true
framework: Docusaurus
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import { CardGrid, LinkCard } from '@astrojs/starlight/components';

[Docusaurus](https://Docusaurus.io) 是一个基于 React 构建的流行的文档网站生成器。

## Docusaurus 和 Astro 之间的主要相似点

Docusaurus 和 Astro 之间有一些相似之处，这将有助于你迁移你的项目：

- Astro 和 Docusaurus 都是现代的、基于 JavaScript（Jamstack）的站点生成器，用于 [内容驱动的网站](/zh-cn/concepts/why-astro/#内容驱动)，如文档站点。

- Astro 和 Docusaurus 都支持 [MDX 页面](/zh-cn/guides/markdown-content/)。你应该能够将现有的 `.mdx` 文件用于Astro。

- Astro 和 Docusaurus 都使用 [基于文件的路由](/zh-cn/guides/routing/) 自动为位于 `src/pages` 的任何 MDX 文件生成页面路由。在 Astro 中为你现有的内容和添加新页面使用文件结构应该会感到熟悉。

- Astro 有一个 [使用 React 组件的官方集成](/zh-cn/guides/integrations-guide/react/)。注意，在 Astro 中，React 文件**必须**有 `.jsx` 或 `.tsx` 扩展名。

- Astro 支持 [安装 NPM 包](/zh-cn/guides/imports/#npm-包)，包括几个 React 的。你可能能保留你现有的部分或全部 React 组件和依赖项。

- [Astro 的类 JSX 语法](/zh-cn/basics/astro-components/#组件模板) 如果你习惯写 React 应该会感觉很熟悉。

## Docusaurus 和 Astro 之间的主要区别

当你在 Astro 中重建你的 Docusaurus 站点时，你会注意到一些重要的区别：

- Docusaurus 是一个基于 React 的单页应用程序(SPA)。Astro 站点是使用 [`.astro` 组件](/zh-cn/basics/astro-components/) 构建的多页应用程序，但也可以支持 [React、Preact、Vue.js、Svelte、SolidJS、AlpineJS](/zh-cn/guides/framework-components/) 和原始 HTML 模板。

- Docusaurus 设计用于构建文档网站，并且有一些内置的，特定于文档的网站功能，你需要在 Astro 中自己构建。相反，Astro 通过 [Starlight：官方文档主题](https://starlight.astro.build) 提供其中一些功能。本网站就是 Starlight 的灵感来源，并且它现在就运行在上面！你还可以在我们的主题展示中找到更多具有内置功能的 [社区文档主题](https://astro.build/themes?search=&categories%5B%5D=docs)。

- Docusaurus 站点使用 MDX 页面进行内容。Astro 的文档主题默认使用 Markdown(`.md`) 文件，并不需要你使用 MDX。你可以选择 [安装 Astro 的 MDX 集成](/zh-cn/guides/integrations-guide/mdx/) (默认包含在我们的 Starlight 主题中) 并使用`.mdx`文件作为标准 Markdown 文件。

## 从 Docusaurus 切换到 Astro

要把一个 Docusaurus 文档站点转换为 Astro，首先使用我们的官方 [Starlight 文档主题启动模板](https://starlight.astro.build)，或者在我们的 [主题展示](https://astro.build/themes?search=&categories%5B%5D=docs) 中探索更多社区文档主题。

你可以向 `create astro` 命令传递一个 `--template` 参数，以一个我们的官方启动器开始一个新的 Astro 项目。或者，你可以 [从 GitHub 上任何现有的 Astro 存储库开始一个新项目](/zh-cn/install-and-setup/#通过-cli-向导安装)。

  <PackageManagerTabs>
    <Fragment slot="npm">
    ```shell
    npm create astro@latest -- --template starlight
    ```
    </Fragment>
    <Fragment slot="pnpm">
    ```shell
    pnpm create astro@latest --template starlight
    ```
    </Fragment>
    <Fragment slot="yarn">
    ```shell
    yarn create astro --template starlight
    ```
    </Fragment>
  </PackageManagerTabs>

Astro 默认就包含了 MDX 的集成，所以你可以立即 [将你现有的内容文件带到 Starlight](https://starlight.astro.build/zh-cn/getting-started/#添加内容)。

你可以在 [astro.new](https://astro.new) 上找到 Astro 的文档启动器和其他官方模板。你会找到每个项目的 GitHub 存储库的链接，以及一键链接到 IDX、StackBlitz、CodeSandbox 和 Gitpod 在线开发环境中的工作项目。

## 社区资源

<CardGrid>

    <LinkCard title="文档处理速度提升 10 倍（俄语）" href="https://habr.com/ru/articles/880220/"/>

</CardGrid>

:::note[有想要分享的资源吗？]
如果你找到（或制作）了关于将 Docusaurus 网站转换为 Astro 的有用的视频或博客文章，请将其 [添加到这个列表中](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-docusaurus.mdx)！
:::
